import { Meta } from '@storybook/addon-docs';

<Meta title="API Reference/Columns" id="api-columns" />

# Column Definitions API

| Property              | Type                             | Required | Example                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------- | -------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                    | string or number                 | no       | RDT will auto generate an id for each column as: 1,2,3..., but you can provide your own id's if you wish as long as each column id is unique. When developing an SSR app you may encounder an `id did not match` warning. In this case, you must explicitly set the `id` to fix the warning                                                                                                                                                                                                                                                                                                                                                                                        |
| name                  | string, component or number      | no       | The display name of our Column e.g. 'Name'. You can also pass a React component in JSX format e.g. `<Title />`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| selector              | `(row, index) => {}`             | no       | A `selector` is required anytime you want to display data but can be omitted if your column does not require showing data (e.g. an actions column)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| format                | `(row, index) => {}`             | no       | Applies formatting to the selector e.g. `row => moment(row.timestamp).format('lll')` without changing the actual selector value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| cell                  | `(row, index, column, id) => {}` | no       | `cell` lets you replace a table cell with your own custom component.<br /><br />If you are using properties such as: `onRowClicked`, `onRowDoubleClicked`, `expandOnRowClicked` or `expandOnRowDoubleClicked` then click events will be ignored when clicking on your custom cell.<br /><br />To allow `RowClicked` events you can add `data-tag="allowRowEvents"` to your custom cell component elements. <br />If your custom cell component is more complex and has nested elements you want to add `data-tag="allowRowEvents"` to the innermost element or on every element you want to propagate the click event to.<br /><br /> **Note:** that using `cell` negates `format` |
| grow                  | number                           | no       | [flex-grow](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow) of the column. This is useful if you want a column to take up more width than its relatives (without having to set widths explicitly). This will be affected by other columns where you have explicitly set widths                                                                                                                                                                                                                                                                                                                                                                                         |
| width                 | string                           | no       | Give the column a fixed width                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| minWidth              | string                           | no       | Give the column a minWidth                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| maxWidth              | string                           | no       | Give the column a maxWidth                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| right                 | boolean                          | no       | Right aligns the content in the cell. useful for numbers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| center                | boolean                          | no       | Center aligns the content in the cell                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| compact               | boolean                          | no       | Sets cell padding to 0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ignoreRowClick        | boolean                          | no       | Prevents the `onRowClicked` and `onRowDoubleClicked` event from being passed on the specific TableCell column. This is useful for a menu or button where you do not want the `onRowClicked` triggered, such as when using `onRowClicked` for navigation or routing                                                                                                                                                                                                                                                                                                                                                                                                      |
| button                | boolean                          | no       | This is like `ignoreRowClick` except it will apply additional styling for button placement. you do not need to set `ignoreRowClick` when using `button`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| wrap                  | boolean                          | no       | Whether the cell content should be allowed to wrap.<br /><br />**Note:** `cell` negates `wrap`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| allowOverflow         | boolean                          | no       | Allows content in the cell to overflow. useful for menus/layovers that do not rely on "smart" positioning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| hide                  | integer or `sm`, `md`, `lg`      | no       | Specify a screen size (breakpoint) as an integer (in pixels) that hides the column when resizing the browser window. You can also use the preset values of: `sm` (small), `md`(medium), and `lg`(large). The default breakpoints are defined [here](#built-in-breakpoints)                                                                                                                                                                                                                                                                                                                                                                                                         |
| omit                  | boolean                          | no       | Omits the column from the table. useful if you need to hide access to data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| sortable              | boolean                          | no       | If the column is sortable.<br /><br />**Note:** `selector` is required for the column to sort                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| sortField             | string                           | no       | This field is typically used with [onSort](/docs/api-props--page#sorting) and when you want to give a specific column a string based name. Another example is remote sorting and when using [sortSever](/docs/api-props--page#sorting) together with `onSort` to call an API for sorting. `sortField` will gives the field you can use to build your sort query url. In this case you would provide the `sortField` to build a URL: `https://api.github.com/search/repositories?q=blog&sort=${column.sortField}&order=${sortDirection}`                                                                                                                                            |
| sortFunction          | `(a, b) => {}`                   | no       | By default RDT uses `Array.sort`, however, you can override the default behavior by passing in a custom sort function. [defining a custom sort function](/docs/api-custom-sorting--page#custom-sorting---sortfunction)                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| reorder               | boolean                          | no       | Allows a column to be dragged and reordered                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| style                 | object                           | no       | Allows you to customize the css of the cell using css-in-js [style objects](https://www.styled-components.com/docs/advanced#style-objects)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| conditionalCellStyles | array                            | no       | Allows an array of [conditional style objects](/docs/api-custom-conditional-formatting--page#conditional-style-object) to conditionally apply css styles to a cell                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

## Built-in Breakpoints

When the breakpoint is reached the column will be hidden. These are the built-in media breakpoint presets when hiding columns:

| Value | Breakpoint | Description                |
| ----- | ---------- | -------------------------- |
| `sm`  | `599px`    | small (phones)             |
| `md`  | `959px`    | medium (landscape tablets) |
| `lg`  | `1280px`   | large (laptops/desktops)   |

# Columns Example

```js
const columns = [
	{
		name: 'Title',
		selector: row => row.title,
	},
	{
		name: 'Year',
		selector: row => row.year,
	},
];
```

# Column ID's

Internally, `columns` require an `id` property. Particularly, the `id` property is required if you use the `defaultSortFieldId` property and you want to define presorted columns by `id`. If you omit `id` from a column object, RDT will autogenerate `id` values starting at 1, 2, 3 and so on. It is, however, recommended that you use your own `id`, which can be either a `string` or a `number`.

```js
const columns = [
	{
		id: 'title',
		name: 'Title',
		selector: row => row.title,
	},
	{
		id: 'year',
		name: 'Year',
		selector: row => row.year,
	},
];
```
